3 Authentication

Many environments require SMTP clients to authenticate themselves before they are allowed to route mail via a server. The two following variables contains the authentication information needed for this.

The first variable, smtpmail-auth-credentials, instructs the SMTP library to use a SASL authentication step, currently only the CRAM-MD5 and LOGIN mechanisms are supported and will be selected in that order if the server support both.

The second variable, smtpmail-starttls-credentials, instructs the SMTP library to connect to the server using STARTTLS. This means the protocol exchange may be integrity protected and confidential by using the Transport Layer Security (TLS) protocol, and optionally also authentication of the client and server.

TLS is a security protocol that is also known as SSL, although strictly speaking, SSL is an older variant of TLS. TLS is backwards compatible with SSL. In most mundane situations, the two terms are equivalent.

The TLS feature uses the elisp package starttls.el (see it for more information on customization), which in turn require that at least one of the following external tools are installed:

1. The GNUTLS command line tool ‘gnutls-cli’, you can get it from http://www.gnu.org/software/gnutls/. This is the recommended tool, mainly because it can verify the server certificates.
2. The ‘starttls’ external program, you can get it from starttls-*.tar.gz from ftp://ftp.opaopa.org/pub/elisp/.

It is not uncommon to use both these mechanisms, e.g., to use STARTTLS to achieve integrity and confidentiality and then use SASL for client authentication.

smtpmail-auth-credentials

The variable smtpmail-auth-credentials contains a list of hostname, port, username and password tuples. When the SMTP library connects to a host on a certain port, this variable is searched to find a matching entry for that hostname and port. If an entry is found, the authentication process is invoked and the credentials are used.

The hostname field follows the same format as smtpmail-smtp-server (i.e., a string) and the port field the same format as smtpmail-smtp-service (i.e., a string or an integer). The username and password fields, which either can be nil to indicate that the user is prompted for the value interactively, should be strings with the username and password, respectively, information that is normally provided by system administrators.

smtpmail-starttls-credentials

The variable smtpmail-starttls-credentials contains a list of tuples with hostname, port, name of file containing client key, and name of file containing client certificate. The processing is similar to the previous variable. The client key and certificate may be nil if you do not wish to use client authentication.

The following example illustrates what you could put in ~/.emacs to enable both SASL authentication and STARTTLS. The server name (smtpmail-smtp-server) is hostname, the server port (smtpmail-smtp-service) is port, and the username and password are username and password respectively.

     ;; Authenticate using this username and password against my server.
     (setq smtpmail-auth-credentials
           '(("hostname" "port" "username" "password")))

     ;; Note that if port is an integer, you must not quote it as a
     ;; string.  Normally port should be the integer 25, and the example
     ;; become:
     (setq smtpmail-auth-credentials
           '(("hostname" 25 "username" "password")))

     ;; Use STARTTLS without authentication against the server.
     (setq smtpmail-starttls-credentials
           '(("hostname" "port" nil nil)))